Documentation Fields

Time to cover the basic fields that apply to all documents. These fields are specified using the '@' character and constitute key value pairs used in rendering your final document.

Sample Key Value Pairs

Documentation is generated through providing the parser with key value pairs. Let's take a look at a few examples:

@id ng.filter:limitTo
@name Sweet Title
@ngdoc directive
@doc overview
@description
## My Markdown Title!

Here is a markdown list
* Yay
* Cool
* Awesome

In every case there is a key next to the "@" symbol and then the value is everything after the key until the next key is found, the code block ends, or the next documentation identifier is encountered. Multiline is supported but is typically used most often for "@description" type keys.

Standard Key Value Pairs

1. @doc / @ngdoc - Documentation Identifier And Doctype

We have covered identifiers in a previous article. But let's talk more about the docType values.

DocType Determines Rendering

This is important to remember. Often times you can get wrapped up in the "@id" given to a document. For example:

@ngdoc filter
@name ng.filter:limitTo

It can be tempting to look at a name/id and assume this document will be rendered as a "filter", but it is the value associated with the document identifier ( @ngdoc filter ) that determines which rendering method is used to generate the html for this document.

Here are the default docTypes for the "@doc" documentation plugin which are inherited by all documentation plugins including the AngularJS documentation plugin.

Here are are docTypes added by the "@ngdoc" AngularJS documentation plugin

The "@ngdoc" documentation api overrides the inherited function from the default plugin to provide a different experience for displaying the function docType.

Visualize This

Picture all these key value pairs getting parsed out and stored in a nice pretty json object. Then this json object needs to be rendered into html. Well, the docType is the identifier that determines which rendering function gets to grab onto all these attributes of this object to spit out html! Easy peezy lemon squeezy.

2. @id

The id is a system used identifier for this doc. It appears in urls and in filenames. It can also determine where the document is placed in terms of grouping unless the docType is "overview" or unless the id value is "index". We'll talk more about that later :-)

3. @name

The name is the user friendly title of the document. If no id is provided, then the name also becomes the id . This is helpful in API documentation when you really want the name and the id to be the same.

4. @description

The description is the meat and potatoes. The description is typically parsed via "Showdown", a NodeJS implementation of markdown. It is a multiline value that provides really whatever you want. One caveat is that you DO NOT want to put markup within markdown! If you need to use markup in your description, then make sure it will not be a child of any markdown or you will get unpredictable results. Taking a look at the source of this documentation will give you a good idea of how to balance markup and markdown. Naturally, sticking with markdown will be lighter weight and will provide more consistency within the ui.